<html>
	<head>
		<title>Managing QFJ Applications with JMX</title>
		<link href="../style.css" rel="stylesheet" type="text/css"/>
	</head>
<body>
<div class="header">
<h1>QuickFIX/J User Manual</h1>
</div>
<h2>Managing QFJ Applications with JMX</h2>
<p>
QuickFIX/J provides FIX engine monitoring and control using
standard Java JMX MBeans. See the
<a href="http://java.sun.com/javase/6/docs/technotes/guides/management/index.html">Java
6 Monitoring and Management</a> information for more details about JMX. Java 5 also
includes built-in support for JMX. External libraries must be used with JDK 1.4
applications. However, this is an option feature so no changes to existing
JDK 1.4 application are required if JMX is not desired.

<h3>QFJ MBeans</h3>
The following MBeans are available:
<ul>
<li>SocketAcceptorAdmin</li>
<li>SocketInitiatorAdmin</li>
<li>SessionAdmin</li>
<li>SessionSettingsAdmin</li>
</ul>

<h3>Adding JMX support to a QFJ application</h3>
MX support is an optional feature. It is enabled for each initiator or acceptor by
using the <code>JmxExporter</code> utility class.

<pre class="code">acceptor = new SocketAcceptor
    (application, messageStoreFactory, settings, logFactory, messageFactory);

<b>JmxExporter jmxExporter = new JmxExporter();
ObjectName connectorObjectName = jmxExporter.register(acceptor);</b>

acceptor.start();

// Later... if you need to unregister the connector MBean
// This should only be needed if you destroying connectors in
// an application (not typical).
<b>jmxExporter.getMBeanServer().unregisterMBean(connectorObjectName);</b>
</pre>

By default, the exporter will try to use the Java 5+ platform MBean server. You can also
create an exporter for an <code>MBeanServer</code> created by the application.

<h3>Accessing JMX MBeans Remotely</h3>

To access JMX MBeans from a separate process (for example, a management console)
a JMX connector must be used. The easiest way to expose the MBeans is to
use Java 6 and the JConsole application included in the Java 6 JDK.
Just start the JConsole application and you will be shown a dialog
that allows you to connect to your QFJ JMX-enabled application.

<p>
<div align="center">
<a href="JConsole.png"><img src="JConsole_thumb.jpg"></a><br/>
<b>QFJ Session Attributes in JConsole</b>
</div>
</p>

<p>
<div align="center">
<a href="JConsole2.png"><img src="JConsole2_thumb.jpg"></a><br/>
<b>QFJ Session Operations in JConsole</b>
</div>
</p>

<p>
Use Java 5, you must add the <code>-Dcom.sun.management.jmxremote</code> system
property when running your QFJ application. This will enable a connector
included with Java 5 that will allow MBeans to be viewed in JConsole
(only on the local machine).
</p>

<p>
Java 1.4 applications must use a separate library to expose the QFJ MBeans.
One very popular option is to use the
<a href="http://mx4j.sourceforge.net/">MX4J library</a>.
MX4J includes standard RMI connector and several other options for exposing
MBeans (including HTTP). See the MX4J documentation for more details.
</p>

<h3>JMX Notifications</h3>
<p>
The QFJ JMX Sesson MBean provides notifications related to state change events.
The JMX notification type is <code>quickfix.Session</code>. The event names are shown
in the following table.
</p>
<table>
<thead>
	<tr>
		<th>Event Name</th><th>Description</th>
	</tr>
</thead>
<tbody>
	<tr>
		<td>connect</td>
		<td>Socket connection associated with session</td>
	</tr>
	<tr>
		<td>disconnect</td>
		<td>Socket connection disassociated from session</td>
	</tr>
	<tr>
		<td>logon</td>
		<td>Session logged on</td>
	</tr>
	<tr>
		<td>logout</td>
		<td>Session logged out</td>
	</tr>
	<tr>
		<td>missedHeartBeat</td>
		<td>Missed heart beat (possible dead connection)</td>
	</tr>
	<tr>
		<td>heartBeatTimeout</td>
		<td>Second heartbeat missed</td>
	</tr>
	<tr>
		<td>refresh</td>
		<td>Session state refreshed from session store.</td>
	</tr>
	<tr>
		<td>reset</td>
		<td>Session state reset</td>
	</tr>
</tbody>
</table>

<h3>Related JMX Management Tools</h3>

JConsole is a convenient tools for accessing JMX MBeans, but there are also
many other options. The following table lists a few examples.

<p>
<table>
<thead>
	<tr>
		<th>Tool</th><th>Type</th><th>Description</th>
	</tr>
</thead>
<tbody>
	<tr>
		<td nowrap="true"><a href="http://visualvm.java.net/">VisualVM</a></td>
		<td>Part of the JDK</td><td></td>
	</tr>
	<tr>
		<td><a href="http://mx4j.sourceforge.net/">MX4J</a></td>
		<td>Open Source</td><td>Includes an HTTP adapter that
			can be embedded in your QFJ process and then accessed through a browser.</td>
	</tr>
	<tr>
		<td><a href="http://mc4j.org/confluence/display/mc4j/Home">MC4J</a></td>
		<td>Open Source</td><td>A management UI build on the NetBeans platform.</td>
	</tr>
	<tr>
		<td><a href="http://www.jmanage.org/">JManage</a></td>
		<td>Open Source</td><td>A web-based management console with
			alerting and monitoring capabilities. It also provides a command line interface. </td>
	</tr>
	<tr>
		<td><a href="http://webjmx.sourceforge.net/">WebJMX</a></td>
		<td>Open Source</td><td>JSP tag library</td>
	</tr>
	<tr>
		<td><a href="http://manageengine.adventnet.com/products/jmx_studio/index.html">AdventNet</a></td>
		<td>Commercial</td><td>See product site.</td>
	</tr>
	<tr>
		<td nowrap="true"><a href="http://devresource.hp.com/drc/slide_presentations/mgJavaApp/index.jsp">HP OpenView</a></td>
		<td>Commercial</td><td>See product site.</td>
	</tr>
</tbody>
</table>
</p>

</body>
</html>
